// 引入Stylelint的Config类型
// 作用：通过TypeScript约束配置对象的结构，确保配置字段符合Stylelint规范
// 同时让IDE能提供精准的代码提示，减少配置语法错误
import type { Config } from 'stylelint';

// 定义Stylelint核心配置对象，指定类型为Config确保配置合规
const config: Config = {
  // 继承外部预设的规则集
  // 继承顺序逻辑：基础校验→扩展规范→框架适配→功能插件，后序规则会覆盖前序冲突规则
  extends: [
    'stylelint-config-recommended', // 基础CSS语法校验，拦截明显错误（如无效CSS属性）
    'stylelint-config-standard', // 扩展CSS最佳实践（如禁止空样式块、禁止重复选择器）
    'stylelint-config-standard-scss', // 适配SCSS语法，支持$变量、@mixin等SCSS特性的校验
    'stylelint-config-recommended-vue', // 适配Vue单文件组件，确保能正确解析.vue中的<style>标签
    'stylelint-config-recess-order', // 配置CSS属性排序规则（按布局→盒模型→排版→视觉的逻辑排序）
    '@stylistic/stylelint-config', // 统一代码格式（如缩进、空格、换行等纯格式规范）
  ],

  // 全局启用的Stylelint插件
  // 作用：为继承的规则集提供功能支持，让规则能正常生效
  plugins: [
    '@stylistic/stylelint-plugin', // 配合@stylistic/stylelint-config，实现格式相关的校验与修复
    'stylelint-order', // 配合stylelint-config-recess-order，实现CSS属性排序功能
    'stylelint-scss', // 提供SCSS专属校验规则（如检测未使用的$变量、非法的SCSS语法）
  ],

  // 全局通用规则配置
  // 作用：对所有未被overrides单独配置的文件生效，优先级低于overrides中的规则
  rules: {
    // 关闭普通CSS中"未知@规则"的校验
    // 适用场景：项目中使用自定义@规则（如框架扩展的@custom-import）时，避免误报错误
    'at-rule-no-unknown': null,

    // 关闭SCSS中"未知@规则"的校验
    // 适用场景：SCSS中使用自定义@mixin或@function时，避免误报错误
    'scss/at-rule-no-unknown': null,

    // 允许使用"未知的CSS属性值"
    // 适用场景：业务中使用自定义主题值（如var(--custom-color)）或特殊属性值时，避免误报
    'declaration-property-value-no-unknown': null,

    // 不限制CSS类名的命名格式
    // 适用场景：允许类名使用驼峰式（.userInfo）、下划线式（.user_info）等多种格式
    'selector-class-pattern': null,

    // 允许存在空样式文件
    // 适用场景：占位符样式文件（暂时无内容，后续补充）不会被判定为错误
    'no-empty-source': null,

    // 配置代码缩进为2个空格
    '@stylistic/indentation': 2,

    // 要求CSS属性冒号后必须保留1个空格
    // 正确示例：color: red；错误示例：color:red
    '@stylistic/declaration-colon-space-after': 'always',

    // 禁止CSS属性冒号前添加空格
    // 正确示例：color: red；错误示例：color : red
    '@stylistic/declaration-colon-space-before': 'never',

    // 要求选择器列表中，逗号后必须换行
    // 正确示例：.a,
    //          .b；错误示例：.a, .b
    '@stylistic/selector-list-comma-newline-after': 'always',

    // 要求样式块的闭合大括号后必须换行
    // 正确示例：.a { color: red }
    //          .b { font-size: 14px }；错误示例：.a { color: red }.b { font-size: 14px }
    '@stylistic/block-closing-brace-newline-after': 'always',

    // 要求小数数值必须带前导零
    // 正确示例：0.5s；错误示例：.5s
    '@stylistic/number-leading-zero': 'always',

    // 要求@规则名称必须使用小写
    // 正确示例：@media；错误示例：@MEDIA、@Media
    '@stylistic/at-rule-name-case': 'lower',
  },

  // 针对不同文件类型的特殊配置
  // 作用：为特定文件定制专属规则，优先级高于全局规则，解决不同文件的解析差异
  overrides: [
    // 1. 处理Vue单文件组件（.vue）
    {
      files: ['**/*.vue'], // 匹配项目中所有.vue文件
      // 使用postcss-html解析器
      // 作用：正确提取.vue文件中<style>标签的内容，避免因Vue模板语法导致的解析错误
      customSyntax: 'postcss-html',
      rules: {
        // 强制关闭Vue文件中"未知@规则"的校验
        // 确保与全局规则一致，避免Vue文件中自定义@规则误报
        'at-rule-no-unknown': null,
        'scss/at-rule-no-unknown': null,
      },
    },

    // 2. 处理独立SCSS文件（.scss）
    {
      files: ['**/*.scss'], // 匹配项目中所有.scss文件
      // 使用postcss-scss解析器
      // 作用：正确识别SCSS语法（如$变量、嵌套规则、@mixin调用），避免解析错误
      customSyntax: 'postcss-scss',
      rules: {
        // 强制关闭SCSS文件中"未知@规则"的校验
        'at-rule-no-unknown': null,
        'scss/at-rule-no-unknown': null,

        // 不限制SCSS中$变量的命名格式
        // 适用场景：允许$变量使用驼峰式（$userName）、下划线式（$user_name）等格式
        'scss/dollar-variable-pattern': null,
      },
    },

    // 3. 处理普通CSS文件（.css）
    {
      files: ['**/*.css'], // 匹配项目中所有.css文件
      rules: {
        // 强制关闭普通CSS文件中"未知@规则"的校验
        // 与全局规则保持一致，确保CSS文件中自定义@规则不被误报
        'at-rule-no-unknown': null,
      },
    },
  ],

  // 配置无需Stylelint校验的文件/目录
  // 作用：减少Stylelint的处理范围，提升校验速度，避免对无关文件的无效校验
  ignoreFiles: [
    // 忽略构建产物和缓存目录（自动生成的文件，无需人工维护）
    'build/**/*',
    'dist/**/*',
    'out/**/*',
    'coverage/**/*',
    '.cache/**/*',

    // 忽略第三方资源目录（非业务代码，无需校验）
    'node_modules/**/*',
    'vendor/**/*',
    'libs/**/*',
    'assets/**/*.min.css',
    'src/styles/normalize.css',

    // 忽略非样式文件（无CSS/SCSS内容，无需校验）
    '*.js',
    '*.ts',
    '*.json',
    '*.md',
    '*.png',
    '*.jpg',
    '*.svg',
    '*.pdf',

    // 忽略特殊功能文件（样式非核心，或已通过其他工具处理）
    '*.d.ts',
    '*.vue?type=script',
    'pages/**/*.wxml',
    '**/*.stories.tsx',

    // 忽略隐藏文件/目录（系统配置或工具配置文件，无需校验）
    '.*',
    '.*/**/*',
  ],
};

// 导出配置对象
// 作用：让Stylelint加载该配置，使所有规则在项目中生效
export default config;
